home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_xemacs.idb / usr / freeware / lib / xemacs-20.4 / info / lispref.info-11.z / lispref.info-11
Encoding:
GNU Info File  |  1998-05-21  |  50.8 KB  |  1,202 lines

  1. This is Info file ../../info/lispref.info, produced by Makeinfo version
  2. 1.68 from the input file lispref.texi.
  3.  
  4.    Edition History:
  5.  
  6.    GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
  7. Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
  8. Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
  9. XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
  10. GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
  11. Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
  12. Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
  13. Reference Manual (for 19.15 and 20.1, 20.2) v3.2, April, May 1997
  14.  
  15.    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
  16. Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
  17. Copyright (C) 1995, 1996 Ben Wing.
  18.  
  19.    Permission is granted to make and distribute verbatim copies of this
  20. manual provided the copyright notice and this permission notice are
  21. preserved on all copies.
  22.  
  23.    Permission is granted to copy and distribute modified versions of
  24. this manual under the conditions for verbatim copying, provided that the
  25. entire resulting derived work is distributed under the terms of a
  26. permission notice identical to this one.
  27.  
  28.    Permission is granted to copy and distribute translations of this
  29. manual into another language, under the above conditions for modified
  30. versions, except that this permission notice may be stated in a
  31. translation approved by the Foundation.
  32.  
  33.    Permission is granted to copy and distribute modified versions of
  34. this manual under the conditions for verbatim copying, provided also
  35. that the section entitled "GNU General Public License" is included
  36. exactly as in the original, and provided that the entire resulting
  37. derived work is distributed under the terms of a permission notice
  38. identical to this one.
  39.  
  40.    Permission is granted to copy and distribute translations of this
  41. manual into another language, under the above conditions for modified
  42. versions, except that the section entitled "GNU General Public License"
  43. may be included in a translation approved by the Free Software
  44. Foundation instead of in the original English.
  45.  
  46. 
  47. File: lispref.info,  Node: Backquote,  Next: Problems with Macros,  Prev: Defining Macros,  Up: Macros
  48.  
  49. Backquote
  50. =========
  51.  
  52.    Macros often need to construct large list structures from a mixture
  53. of constants and nonconstant parts.  To make this easier, use the macro
  54. ``' (often called "backquote").
  55.  
  56.    Backquote allows you to quote a list, but selectively evaluate
  57. elements of that list.  In the simplest case, it is identical to the
  58. special form `quote' (*note Quoting::.).  For example, these two forms
  59. yield identical results:
  60.  
  61.      `(a list of (+ 2 3) elements)
  62.           => (a list of (+ 2 3) elements)
  63.      '(a list of (+ 2 3) elements)
  64.           => (a list of (+ 2 3) elements)
  65.  
  66.    The special marker `,' inside of the argument to backquote indicates
  67. a value that isn't constant.  Backquote evaluates the argument of `,'
  68. and puts the value in the list structure:
  69.  
  70.      (list 'a 'list 'of (+ 2 3) 'elements)
  71.           => (a list of 5 elements)
  72.      `(a list of ,(+ 2 3) elements)
  73.           => (a list of 5 elements)
  74.  
  75.    You can also "splice" an evaluated value into the resulting list,
  76. using the special marker `,@'.  The elements of the spliced list become
  77. elements at the same level as the other elements of the resulting list.
  78. The equivalent code without using ``' is often unreadable.  Here are
  79. some examples:
  80.  
  81.      (setq some-list '(2 3))
  82.           => (2 3)
  83.      (cons 1 (append some-list '(4) some-list))
  84.           => (1 2 3 4 2 3)
  85.      `(1 ,@some-list 4 ,@some-list)
  86.           => (1 2 3 4 2 3)
  87.      
  88.      (setq list '(hack foo bar))
  89.           => (hack foo bar)
  90.      (cons 'use
  91.        (cons 'the
  92.          (cons 'words (append (cdr list) '(as elements)))))
  93.           => (use the words foo bar as elements)
  94.      `(use the words ,@(cdr list) as elements)
  95.           => (use the words foo bar as elements)
  96.  
  97.      Before Emacs version 19.29, ``' used a different syntax which
  98.      required an extra level of parentheses around the entire backquote
  99.      construct.  Likewise, each `,' or `,@' substitution required an
  100.      extra level of parentheses surrounding both the `,' or `,@' and
  101.      the following expression.  The old syntax required whitespace
  102.      between the ``', `,' or `,@' and the following expression.
  103.  
  104.      This syntax is still accepted, but no longer recommended except for
  105.      compatibility with old Emacs versions.
  106.  
  107. 
  108. File: lispref.info,  Node: Problems with Macros,  Prev: Backquote,  Up: Macros
  109.  
  110. Common Problems Using Macros
  111. ============================
  112.  
  113.    The basic facts of macro expansion have counterintuitive
  114. consequences.  This section describes some important consequences that
  115. can lead to trouble, and rules to follow to avoid trouble.
  116.  
  117. * Menu:
  118.  
  119. * Argument Evaluation::    The expansion should evaluate each macro arg once.
  120. * Surprising Local Vars::  Local variable bindings in the expansion
  121.                               require special care.
  122. * Eval During Expansion::  Don't evaluate them; put them in the expansion.
  123. * Repeated Expansion::     Avoid depending on how many times expansion is done.
  124.  
  125. 
  126. File: lispref.info,  Node: Argument Evaluation,  Next: Surprising Local Vars,  Up: Problems with Macros
  127.  
  128. Evaluating Macro Arguments Repeatedly
  129. -------------------------------------
  130.  
  131.    When defining a macro you must pay attention to the number of times
  132. the arguments will be evaluated when the expansion is executed.  The
  133. following macro (used to facilitate iteration) illustrates the problem.
  134. This macro allows us to write a simple "for" loop such as one might
  135. find in Pascal.
  136.  
  137.      (defmacro for (var from init to final do &rest body)
  138.        "Execute a simple \"for\" loop.
  139.      For example, (for i from 1 to 10 do (print i))."
  140.        (list 'let (list (list var init))
  141.              (cons 'while (cons (list '<= var final)
  142.                                 (append body (list (list 'inc var)))))))
  143.      => for
  144.      (for i from 1 to 3 do
  145.         (setq square (* i i))
  146.         (princ (format "\n%d %d" i square)))
  147.      ==>
  148.  
  149.      (let ((i 1))
  150.        (while (<= i 3)
  151.          (setq square (* i i))
  152.          (princ (format "%d      %d" i square))
  153.          (inc i)))
  154.  
  155.  
  156.      -|1       1
  157.           -|2       4
  158.           -|3       9
  159.      => nil
  160.  
  161. (The arguments `from', `to', and `do' in this macro are "syntactic
  162. sugar"; they are entirely ignored.  The idea is that you will write
  163. noise words (such as `from', `to', and `do') in those positions in the
  164. macro call.)
  165.  
  166.    Here's an equivalent definition simplified through use of backquote:
  167.  
  168.      (defmacro for (var from init to final do &rest body)
  169.        "Execute a simple \"for\" loop.
  170.      For example, (for i from 1 to 10 do (print i))."
  171.        `(let ((,var ,init))
  172.           (while (<= ,var ,final)
  173.             ,@body
  174.             (inc ,var))))
  175.  
  176.    Both forms of this definition (with backquote and without) suffer
  177. from the defect that FINAL is evaluated on every iteration.  If FINAL
  178. is a constant, this is not a problem.  If it is a more complex form,
  179. say `(long-complex-calculation x)', this can slow down the execution
  180. significantly.  If FINAL has side effects, executing it more than once
  181. is probably incorrect.
  182.  
  183.    A well-designed macro definition takes steps to avoid this problem by
  184. producing an expansion that evaluates the argument expressions exactly
  185. once unless repeated evaluation is part of the intended purpose of the
  186. macro.  Here is a correct expansion for the `for' macro:
  187.  
  188.      (let ((i 1)
  189.            (max 3))
  190.        (while (<= i max)
  191.          (setq square (* i i))
  192.          (princ (format "%d      %d" i square))
  193.          (inc i)))
  194.  
  195.    Here is a macro definition that creates this expansion:
  196.  
  197.      (defmacro for (var from init to final do &rest body)
  198.        "Execute a simple for loop: (for i from 1 to 10 do (print i))."
  199.        `(let ((,var ,init)
  200.               (max ,final))
  201.           (while (<= ,var max)
  202.             ,@body
  203.             (inc ,var))))
  204.  
  205.    Unfortunately, this introduces another problem.  Proceed to the
  206. following node.
  207.  
  208. 
  209. File: lispref.info,  Node: Surprising Local Vars,  Next: Eval During Expansion,  Prev: Argument Evaluation,  Up: Problems with Macros
  210.  
  211. Local Variables in Macro Expansions
  212. -----------------------------------
  213.  
  214.    In the previous section, the definition of `for' was fixed as
  215. follows to make the expansion evaluate the macro arguments the proper
  216. number of times:
  217.  
  218.      (defmacro for (var from init to final do &rest body)
  219.        "Execute a simple for loop: (for i from 1 to 10 do (print i))."
  220.  
  221.      `(let ((,var ,init)
  222.               (max ,final))
  223.           (while (<= ,var max)
  224.             ,@body
  225.             (inc ,var))))
  226.  
  227.    The new definition of `for' has a new problem: it introduces a local
  228. variable named `max' which the user does not expect.  This causes
  229. trouble in examples such as the following:
  230.  
  231.      (let ((max 0))
  232.        (for x from 0 to 10 do
  233.          (let ((this (frob x)))
  234.            (if (< max this)
  235.                (setq max this)))))
  236.  
  237. The references to `max' inside the body of the `for', which are
  238. supposed to refer to the user's binding of `max', really access the
  239. binding made by `for'.
  240.  
  241.    The way to correct this is to use an uninterned symbol instead of
  242. `max' (*note Creating Symbols::.).  The uninterned symbol can be bound
  243. and referred to just like any other symbol, but since it is created by
  244. `for', we know that it cannot already appear in the user's program.
  245. Since it is not interned, there is no way the user can put it into the
  246. program later.  It will never appear anywhere except where put by
  247. `for'.  Here is a definition of `for' that works this way:
  248.  
  249.      (defmacro for (var from init to final do &rest body)
  250.        "Execute a simple for loop: (for i from 1 to 10 do (print i))."
  251.        (let ((tempvar (make-symbol "max")))
  252.          `(let ((,var ,init)
  253.                 (,tempvar ,final))
  254.             (while (<= ,var ,tempvar)
  255.               ,@body
  256.               (inc ,var)))))
  257.  
  258. This creates an uninterned symbol named `max' and puts it in the
  259. expansion instead of the usual interned symbol `max' that appears in
  260. expressions ordinarily.
  261.  
  262. 
  263. File: lispref.info,  Node: Eval During Expansion,  Next: Repeated Expansion,  Prev: Surprising Local Vars,  Up: Problems with Macros
  264.  
  265. Evaluating Macro Arguments in Expansion
  266. ---------------------------------------
  267.  
  268.    Another problem can happen if you evaluate any of the macro argument
  269. expressions during the computation of the expansion, such as by calling
  270. `eval' (*note Eval::.).  If the argument is supposed to refer to the
  271. user's variables, you may have trouble if the user happens to use a
  272. variable with the same name as one of the macro arguments.  Inside the
  273. macro body, the macro argument binding is the most local binding of this
  274. variable, so any references inside the form being evaluated do refer to
  275. it.  Here is an example:
  276.  
  277.      (defmacro foo (a)
  278.        (list 'setq (eval a) t))
  279.           => foo
  280.      (setq x 'b)
  281.      (foo x) ==> (setq b t)
  282.           => t                  ; and `b' has been set.
  283.      ;; but
  284.      (setq a 'c)
  285.      (foo a) ==> (setq a t)
  286.           => t                  ; but this set `a', not `c'.
  287.  
  288.    It makes a difference whether the user's variable is named `a' or
  289. `x', because `a' conflicts with the macro argument variable `a'.
  290.  
  291.    Another reason not to call `eval' in a macro definition is that it
  292. probably won't do what you intend in a compiled program.  The
  293. byte-compiler runs macro definitions while compiling the program, when
  294. the program's own computations (which you might have wished to access
  295. with `eval') don't occur and its local variable bindings don't exist.
  296.  
  297.    The safe way to work with the run-time value of an expression is to
  298. put the expression into the macro expansion, so that its value is
  299. computed as part of executing the expansion.
  300.  
  301. 
  302. File: lispref.info,  Node: Repeated Expansion,  Prev: Eval During Expansion,  Up: Problems with Macros
  303.  
  304. How Many Times is the Macro Expanded?
  305. -------------------------------------
  306.  
  307.    Occasionally problems result from the fact that a macro call is
  308. expanded each time it is evaluated in an interpreted function, but is
  309. expanded only once (during compilation) for a compiled function.  If the
  310. macro definition has side effects, they will work differently depending
  311. on how many times the macro is expanded.
  312.  
  313.    In particular, constructing objects is a kind of side effect.  If the
  314. macro is called once, then the objects are constructed only once.  In
  315. other words, the same structure of objects is used each time the macro
  316. call is executed.  In interpreted operation, the macro is reexpanded
  317. each time, producing a fresh collection of objects each time.  Usually
  318. this does not matter--the objects have the same contents whether they
  319. are shared or not.  But if the surrounding program does side effects on
  320. the objects, it makes a difference whether they are shared.  Here is an
  321. example:
  322.  
  323.      (defmacro empty-object ()
  324.        (list 'quote (cons nil nil)))
  325.  
  326.      (defun initialize (condition)
  327.        (let ((object (empty-object)))
  328.          (if condition
  329.              (setcar object condition))
  330.          object))
  331.  
  332. If `initialize' is interpreted, a new list `(nil)' is constructed each
  333. time `initialize' is called.  Thus, no side effect survives between
  334. calls.  If `initialize' is compiled, then the macro `empty-object' is
  335. expanded during compilation, producing a single "constant" `(nil)' that
  336. is reused and altered each time `initialize' is called.
  337.  
  338.    One way to avoid pathological cases like this is to think of
  339. `empty-object' as a funny kind of constant, not as a memory allocation
  340. construct.  You wouldn't use `setcar' on a constant such as `'(nil)',
  341. so naturally you won't use it on `(empty-object)' either.
  342.  
  343. 
  344. File: lispref.info,  Node: Loading,  Next: Byte Compilation,  Prev: Macros,  Up: Top
  345.  
  346. Loading
  347. *******
  348.  
  349.    Loading a file of Lisp code means bringing its contents into the Lisp
  350. environment in the form of Lisp objects.  XEmacs finds and opens the
  351. file, reads the text, evaluates each form, and then closes the file.
  352.  
  353.    The load functions evaluate all the expressions in a file just as
  354. the `eval-current-buffer' function evaluates all the expressions in a
  355. buffer.  The difference is that the load functions read and evaluate
  356. the text in the file as found on disk, not the text in an Emacs buffer.
  357.  
  358.    The loaded file must contain Lisp expressions, either as source code
  359. or as byte-compiled code.  Each form in the file is called a "top-level
  360. form".  There is no special format for the forms in a loadable file;
  361. any form in a file may equally well be typed directly into a buffer and
  362. evaluated there.  (Indeed, most code is tested this way.)  Most often,
  363. the forms are function definitions and variable definitions.
  364.  
  365.    A file containing Lisp code is often called a "library".  Thus, the
  366. "Rmail library" is a file containing code for Rmail mode.  Similarly, a
  367. "Lisp library directory" is a directory of files containing Lisp code.
  368.  
  369. * Menu:
  370.  
  371. * How Programs Do Loading::     The `load' function and others.
  372. * Autoload::                    Setting up a function to autoload.
  373. * Repeated Loading::            Precautions about loading a file twice.
  374. * Named Features::              Loading a library if it isn't already loaded.
  375. * Unloading::            How to "unload" a library that was loaded.
  376. * Hooks for Loading::        Providing code to be run when
  377.                   particular libraries are loaded.
  378.  
  379. 
  380. File: lispref.info,  Node: How Programs Do Loading,  Next: Autoload,  Up: Loading
  381.  
  382. How Programs Do Loading
  383. =======================
  384.  
  385.    XEmacs Lisp has several interfaces for loading.  For example,
  386. `autoload' creates a placeholder object for a function in a file;
  387. trying to call the autoloading function loads the file to get the
  388. function's real definition (*note Autoload::.).  `require' loads a file
  389. if it isn't already loaded (*note Named Features::.).  Ultimately, all
  390. these facilities call the `load' function to do the work.
  391.  
  392.  - Function: load FILENAME &optional MISSING-OK NOMESSAGE NOSUFFIX
  393.      This function finds and opens a file of Lisp code, evaluates all
  394.      the forms in it, and closes the file.
  395.  
  396.      To find the file, `load' first looks for a file named
  397.      `FILENAME.elc', that is, for a file whose name is FILENAME with
  398.      `.elc' appended.  If such a file exists, it is loaded.  If there
  399.      is no file by that name, then `load' looks for a file named
  400.      `FILENAME.el'.  If that file exists, it is loaded.  Finally, if
  401.      neither of those names is found, `load' looks for a file named
  402.      FILENAME with nothing appended, and loads it if it exists.  (The
  403.      `load' function is not clever about looking at FILENAME.  In the
  404.      perverse case of a file named `foo.el.el', evaluation of `(load
  405.      "foo.el")' will indeed find it.)
  406.  
  407.      If the optional argument NOSUFFIX is non-`nil', then the suffixes
  408.      `.elc' and `.el' are not tried.  In this case, you must specify
  409.      the precise file name you want.
  410.  
  411.      If FILENAME is a relative file name, such as `foo' or
  412.      `baz/foo.bar', `load' searches for the file using the variable
  413.      `load-path'.  It appends FILENAME to each of the directories
  414.      listed in `load-path', and loads the first file it finds whose name
  415.      matches.  The current default directory is tried only if it is
  416.      specified in `load-path', where `nil' stands for the default
  417.      directory.  `load' tries all three possible suffixes in the first
  418.      directory in `load-path', then all three suffixes in the second
  419.      directory, and so on.
  420.  
  421.      If you get a warning that `foo.elc' is older than `foo.el', it
  422.      means you should consider recompiling `foo.el'.  *Note Byte
  423.      Compilation::.
  424.  
  425.      Messages like `Loading foo...' and `Loading foo...done' appear in
  426.      the echo area during loading unless NOMESSAGE is non-`nil'.
  427.  
  428.      Any unhandled errors while loading a file terminate loading.  If
  429.      the load was done for the sake of `autoload', any function
  430.      definitions made during the loading are undone.
  431.  
  432.      If `load' can't find the file to load, then normally it signals the
  433.      error `file-error' (with `Cannot open load file FILENAME').  But
  434.      if MISSING-OK is non-`nil', then `load' just returns `nil'.
  435.  
  436.      You can use the variable `load-read-function' to specify a function
  437.      for `load' to use instead of `read' for reading expressions.  See
  438.      below.
  439.  
  440.      `load' returns `t' if the file loads successfully.
  441.  
  442.  - User Option: load-path
  443.      The value of this variable is a list of directories to search when
  444.      loading files with `load'.  Each element is a string (which must be
  445.      a directory name) or `nil' (which stands for the current working
  446.      directory).  The value of `load-path' is initialized from the
  447.      environment variable `EMACSLOADPATH', if that exists; otherwise its
  448.      default value is specified in `emacs/src/paths.h' when XEmacs is
  449.      built.
  450.  
  451.      The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:'
  452.      (or `;', according to the operating system) separates directory
  453.      names, and `.' is used for the current default directory.  Here is
  454.      an example of how to set your `EMACSLOADPATH' variable from a
  455.      `csh' `.login' file:
  456.  
  457.           setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
  458.  
  459.      Here is how to set it using `sh':
  460.  
  461.           export EMACSLOADPATH
  462.           EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
  463.  
  464.      Here is an example of code you can place in a `.emacs' file to add
  465.      several directories to the front of your default `load-path':
  466.  
  467.           (setq load-path
  468.                 (append (list nil "/user/bil/emacs"
  469.                               "/usr/local/lisplib"
  470.                               "~/emacs")
  471.                         load-path))
  472.  
  473.      In this example, the path searches the current working directory
  474.      first, followed then by the `/user/bil/emacs' directory, the
  475.      `/usr/local/lisplib' directory, and the `~/emacs' directory, which
  476.      are then followed by the standard directories for Lisp code.
  477.  
  478.      The command line options `-l' or `-load' specify a Lisp library to
  479.      load as part of Emacs startup.  Since this file might be in the
  480.      current directory, Emacs 18 temporarily adds the current directory
  481.      to the front of `load-path' so the file can be found there.  Newer
  482.      Emacs versions also find such files in the current directory, but
  483.      without altering `load-path'.
  484.  
  485.      Dumping Emacs uses a special value of `load-path'.  If the value of
  486.      `load-path' at the end of dumping is unchanged (that is, still the
  487.      same special value), the dumped Emacs switches to the ordinary
  488.      `load-path' value when it starts up, as described above.  But if
  489.      `load-path' has any other value at the end of dumping, that value
  490.      is used for execution of the dumped Emacs also.
  491.  
  492.      Therefore, if you want to change `load-path' temporarily for
  493.      loading a few libraries in `site-init.el' or `site-load.el', you
  494.      should bind `load-path' locally with `let' around the calls to
  495.      `load'.
  496.  
  497.  - Function: locate-file FILENAME PATH-LIST &optional SUFFIXES MODE
  498.      This function searches for a file in the same way that `load' does,
  499.      and returns the file found (if any). (In fact, `load' uses this
  500.      function to search through `load-path'.) It searches for FILENAME
  501.      through PATH-LIST, expanded by one of the optional SUFFIXES
  502.      (string of suffixes separated by `:'s), checking for access MODE
  503.      (0|1|2|4 = exists|executable|writeable|readable), default readable.
  504.  
  505.      `locate-file' keeps hash tables of the directories it searches
  506.      through, in order to speed things up.  It tries valiantly to not
  507.      get confused in the face of a changing and unpredictable
  508.      environment, but can occasionally get tripped up.  In this case,
  509.      you will have to call `locate-file-clear-hashing' to get it back
  510.      on track.  See that function for details.
  511.  
  512.  - Function: locate-file-clear-hashing PATH
  513.      This function clears the hash records for the specified list of
  514.      directories.  `locate-file' uses a hashing scheme to speed lookup,
  515.      and will correctly track the following environmental changes:
  516.  
  517.         * changes of any sort to the list of directories to be searched.
  518.  
  519.         * addition and deletion of non-shadowing files (see below) from
  520.           the directories in the list.
  521.  
  522.         * byte-compilation of a .el file into a .elc file.
  523.  
  524.      `locate-file' will primarily get confused if you add a file that
  525.      shadows (i.e. has the same name as) another file further down in
  526.      the directory list.  In this case, you must call
  527.      `locate-file-clear-hashing'.
  528.  
  529.  - Variable: load-in-progress
  530.      This variable is non-`nil' if Emacs is in the process of loading a
  531.      file, and it is `nil' otherwise.
  532.  
  533.  - Variable: load-read-function
  534.      This variable specifies an alternate expression-reading function
  535.      for `load' and `eval-region' to use instead of `read'.  The
  536.      function should accept one argument, just as `read' does.
  537.  
  538.      Normally, the variable's value is `nil', which means those
  539.      functions should use `read'.
  540.  
  541.  - User Option: load-warn-when-source-newer
  542.      This variable specifies whether `load' should check whether the
  543.      source is newer than the binary.  If this variable is true, then
  544.      when a `.elc' file is being loaded and the corresponding `.el' is
  545.      newer, a warning message will be printed.  The default is `nil',
  546.      but it is bound to `t' during the initial loadup.
  547.  
  548.  - User Option: load-warn-when-source-only
  549.      This variable specifies whether `load' should warn when loading a
  550.      `.el' file instead of an `.elc'.  If this variable is true, then
  551.      when `load' is called with a filename without an extension, and
  552.      the `.elc' version doesn't exist but the `.el' version does, then
  553.      a message will be printed.  If an explicit extension is passed to
  554.      `load', no warning will be printed.  The default is `nil', but it
  555.      is bound to `t' during the initial loadup.
  556.  
  557.  - User Option: load-ignore-elc-files
  558.      This variable specifies whether `load' should ignore `.elc' files
  559.      when a suffix is not given.  This is normally used only to
  560.      bootstrap the `.elc' files when building XEmacs, when you use the
  561.      command `make all-elc'. (This forces the `.el' versions to be
  562.      loaded in the process of compiling those same files, so that
  563.      existing out-of-date `.elc' files do not make it mess things up.)
  564.  
  565.    To learn how `load' is used to build XEmacs, see *Note Building
  566. XEmacs::.
  567.  
  568. 
  569. File: lispref.info,  Node: Autoload,  Next: Repeated Loading,  Prev: How Programs Do Loading,  Up: Loading
  570.  
  571. Autoload
  572. ========
  573.  
  574.    The "autoload" facility allows you to make a function or macro known
  575. in Lisp, but put off loading the file that defines it.  The first call
  576. to the function automatically reads the proper file to install the real
  577. definition and other associated code, then runs the real definition as
  578. if it had been loaded all along.
  579.  
  580.    There are two ways to set up an autoloaded function: by calling
  581. `autoload', and by writing a special "magic" comment in the source
  582. before the real definition.  `autoload' is the low-level primitive for
  583. autoloading; any Lisp program can call `autoload' at any time.  Magic
  584. comments do nothing on their own; they serve as a guide for the command
  585. `update-file-autoloads', which constructs calls to `autoload' and
  586. arranges to execute them when Emacs is built.  Magic comments are the
  587. most convenient way to make a function autoload, but only for packages
  588. installed along with Emacs.
  589.  
  590.  - Function: autoload FUNCTION FILENAME &optional DOCSTRING INTERACTIVE
  591.           TYPE
  592.      This function defines the function (or macro) named FUNCTION so as
  593.      to load automatically from FILENAME.  The string FILENAME
  594.      specifies the file to load to get the real definition of FUNCTION.
  595.  
  596.      The argument DOCSTRING is the documentation string for the
  597.      function.  Normally, this is the identical to the documentation
  598.      string in the function definition itself.  Specifying the
  599.      documentation string in the call to `autoload' makes it possible
  600.      to look at the documentation without loading the function's real
  601.      definition.
  602.  
  603.      If INTERACTIVE is non-`nil', then the function can be called
  604.      interactively.  This lets completion in `M-x' work without loading
  605.      the function's real definition.  The complete interactive
  606.      specification need not be given here; it's not needed unless the
  607.      user actually calls FUNCTION, and when that happens, it's time to
  608.      load the real definition.
  609.  
  610.      You can autoload macros and keymaps as well as ordinary functions.
  611.      Specify TYPE as `macro' if FUNCTION is really a macro.  Specify
  612.      TYPE as `keymap' if FUNCTION is really a keymap.  Various parts of
  613.      Emacs need to know this information without loading the real
  614.      definition.
  615.  
  616.      An autoloaded keymap loads automatically during key lookup when a
  617.      prefix key's binding is the symbol FUNCTION.  Autoloading does not
  618.      occur for other kinds of access to the keymap.  In particular, it
  619.      does not happen when a Lisp program gets the keymap from the value
  620.      of a variable and calls `define-key'; not even if the variable
  621.      name is the same symbol FUNCTION.
  622.  
  623.      If FUNCTION already has a non-void function definition that is not
  624.      an autoload object, `autoload' does nothing and returns `nil'.  If
  625.      the function cell of FUNCTION is void, or is already an autoload
  626.      object, then it is defined as an autoload object like this:
  627.  
  628.           (autoload FILENAME DOCSTRING INTERACTIVE TYPE)
  629.  
  630.      For example,
  631.  
  632.           (symbol-function 'run-prolog)
  633.                => (autoload "prolog" 169681 t nil)
  634.  
  635.      In this case, `"prolog"' is the name of the file to load, 169681
  636.      refers to the documentation string in the `DOC' file (*note
  637.      Documentation Basics::.), `t' means the function is interactive,
  638.      and `nil' that it is not a macro or a keymap.
  639.  
  640.    The autoloaded file usually contains other definitions and may
  641. require or provide one or more features.  If the file is not completely
  642. loaded (due to an error in the evaluation of its contents), any function
  643. definitions or `provide' calls that occurred during the load are
  644. undone.  This is to ensure that the next attempt to call any function
  645. autoloading from this file will try again to load the file.  If not for
  646. this, then some of the functions in the file might appear defined, but
  647. they might fail to work properly for the lack of certain subroutines
  648. defined later in the file and not loaded successfully.
  649.  
  650.    XEmacs as distributed comes with many autoloaded functions.  The
  651. calls to `autoload' are in the file `loaddefs.el'.  There is a
  652. convenient way of updating them automatically.
  653.  
  654.    If the autoloaded file fails to define the desired Lisp function or
  655. macro, then an error is signaled with data `"Autoloading failed to
  656. define function FUNCTION-NAME"'.
  657.  
  658.    A magic autoload comment looks like `;;;###autoload', on a line by
  659. itself, just before the real definition of the function in its
  660. autoloadable source file.  The command `M-x update-file-autoloads'
  661. writes a corresponding `autoload' call into `loaddefs.el'.  Building
  662. Emacs loads `loaddefs.el' and thus calls `autoload'.  `M-x
  663. update-directory-autoloads' is even more powerful; it updates autoloads
  664. for all files in the current directory.
  665.  
  666.    The same magic comment can copy any kind of form into `loaddefs.el'.
  667. If the form following the magic comment is not a function definition,
  668. it is copied verbatim.  You can also use a magic comment to execute a
  669. form at build time *without* executing it when the file itself is
  670. loaded.  To do this, write the form "on the same line" as the magic
  671. comment.  Since it is in a comment, it does nothing when you load the
  672. source file; but `update-file-autoloads' copies it to `loaddefs.el',
  673. where it is executed while building Emacs.
  674.  
  675.    The following example shows how `doctor' is prepared for autoloading
  676. with a magic comment:
  677.  
  678.      ;;;###autoload
  679.      (defun doctor ()
  680.        "Switch to *doctor* buffer and start giving psychotherapy."
  681.        (interactive)
  682.        (switch-to-buffer "*doctor*")
  683.        (doctor-mode))
  684.  
  685. Here's what that produces in `loaddefs.el':
  686.  
  687.      (autoload 'doctor "doctor"
  688.        "\
  689.      Switch to *doctor* buffer and start giving psychotherapy."
  690.        t)
  691.  
  692. The backslash and newline immediately following the double-quote are a
  693. convention used only in the preloaded Lisp files such as `loaddefs.el';
  694. they tell `make-docfile' to put the documentation string in the `DOC'
  695. file.  *Note Building XEmacs::.
  696.  
  697. 
  698. File: lispref.info,  Node: Repeated Loading,  Next: Named Features,  Prev: Autoload,  Up: Loading
  699.  
  700. Repeated Loading
  701. ================
  702.  
  703.    You may load one file more than once in an Emacs session.  For
  704. example, after you have rewritten and reinstalled a function definition
  705. by editing it in a buffer, you may wish to return to the original
  706. version; you can do this by reloading the file it came from.
  707.  
  708.    When you load or reload files, bear in mind that the `load' and
  709. `load-library' functions automatically load a byte-compiled file rather
  710. than a non-compiled file of similar name.  If you rewrite a file that
  711. you intend to save and reinstall, remember to byte-compile it if
  712. necessary; otherwise you may find yourself inadvertently reloading the
  713. older, byte-compiled file instead of your newer, non-compiled file!
  714.  
  715.    When writing the forms in a Lisp library file, keep in mind that the
  716. file might be loaded more than once.  For example, the choice of
  717. `defvar' vs. `defconst' for defining a variable depends on whether it
  718. is desirable to reinitialize the variable if the library is reloaded:
  719. `defconst' does so, and `defvar' does not.  (*Note Defining
  720. Variables::.)
  721.  
  722.    The simplest way to add an element to an alist is like this:
  723.  
  724.      (setq minor-mode-alist
  725.            (cons '(leif-mode " Leif") minor-mode-alist))
  726.  
  727. But this would add multiple elements if the library is reloaded.  To
  728. avoid the problem, write this:
  729.  
  730.      (or (assq 'leif-mode minor-mode-alist)
  731.          (setq minor-mode-alist
  732.                (cons '(leif-mode " Leif") minor-mode-alist)))
  733.  
  734.    To add an element to a list just once, use `add-to-list' (*note
  735. Setting Variables::.).
  736.  
  737.    Occasionally you will want to test explicitly whether a library has
  738. already been loaded.  Here's one way to test, in a library, whether it
  739. has been loaded before:
  740.  
  741.      (defvar foo-was-loaded)
  742.      
  743.      (if (not (boundp 'foo-was-loaded))
  744.          EXECUTE-FIRST-TIME-ONLY)
  745.      
  746.      (setq foo-was-loaded t)
  747.  
  748. If the library uses `provide' to provide a named feature, you can use
  749. `featurep' to test whether the library has been loaded.  *Note Named
  750. Features::.
  751.  
  752. 
  753. File: lispref.info,  Node: Named Features,  Next: Unloading,  Prev: Repeated Loading,  Up: Loading
  754.  
  755. Features
  756. ========
  757.  
  758.    `provide' and `require' are an alternative to `autoload' for loading
  759. files automatically.  They work in terms of named "features".
  760. Autoloading is triggered by calling a specific function, but a feature
  761. is loaded the first time another program asks for it by name.
  762.  
  763.    A feature name is a symbol that stands for a collection of functions,
  764. variables, etc.  The file that defines them should "provide" the
  765. feature.  Another program that uses them may ensure they are defined by
  766. "requiring" the feature.  This loads the file of definitions if it
  767. hasn't been loaded already.
  768.  
  769.    To require the presence of a feature, call `require' with the
  770. feature name as argument.  `require' looks in the global variable
  771. `features' to see whether the desired feature has been provided
  772. already.  If not, it loads the feature from the appropriate file.  This
  773. file should call `provide' at the top level to add the feature to
  774. `features'; if it fails to do so, `require' signals an error.
  775.  
  776.    Features are normally named after the files that provide them, so
  777. that `require' need not be given the file name.
  778.  
  779.    For example, in `emacs/lisp/prolog.el', the definition for
  780. `run-prolog' includes the following code:
  781.  
  782.      (defun run-prolog ()
  783.        "Run an inferior Prolog process, input and output via buffer *prolog*."
  784.        (interactive)
  785.        (require 'comint)
  786.        (switch-to-buffer (make-comint "prolog" prolog-program-name))
  787.        (inferior-prolog-mode))
  788.  
  789. The expression `(require 'comint)' loads the file `comint.el' if it has
  790. not yet been loaded.  This ensures that `make-comint' is defined.
  791.  
  792.    The `comint.el' file contains the following top-level expression:
  793.  
  794.      (provide 'comint)
  795.  
  796. This adds `comint' to the global `features' list, so that `(require
  797. 'comint)' will henceforth know that nothing needs to be done.
  798.  
  799.    When `require' is used at top level in a file, it takes effect when
  800. you byte-compile that file (*note Byte Compilation::.) as well as when
  801. you load it.  This is in case the required package contains macros that
  802. the byte compiler must know about.
  803.  
  804.    Although top-level calls to `require' are evaluated during byte
  805. compilation, `provide' calls are not.  Therefore, you can ensure that a
  806. file of definitions is loaded before it is byte-compiled by including a
  807. `provide' followed by a `require' for the same feature, as in the
  808. following example.
  809.  
  810.      (provide 'my-feature)  ; Ignored by byte compiler,
  811.                             ;   evaluated by `load'.
  812.      (require 'my-feature)  ; Evaluated by byte compiler.
  813.  
  814. The compiler ignores the `provide', then processes the `require' by
  815. loading the file in question.  Loading the file does execute the
  816. `provide' call, so the subsequent `require' call does nothing while
  817. loading.
  818.  
  819.  - Function: provide FEATURE
  820.      This function announces that FEATURE is now loaded, or being
  821.      loaded, into the current XEmacs session.  This means that the
  822.      facilities associated with FEATURE are or will be available for
  823.      other Lisp programs.
  824.  
  825.      The direct effect of calling `provide' is to add FEATURE to the
  826.      front of the list `features' if it is not already in the list.
  827.      The argument FEATURE must be a symbol.  `provide' returns FEATURE.
  828.  
  829.           features
  830.                => (bar bish)
  831.           
  832.           (provide 'foo)
  833.                => foo
  834.           features
  835.                => (foo bar bish)
  836.  
  837.      When a file is loaded to satisfy an autoload, and it stops due to
  838.      an error in the evaluating its contents, any function definitions
  839.      or `provide' calls that occurred during the load are undone.
  840.      *Note Autoload::.
  841.  
  842.  - Function: require FEATURE &optional FILENAME
  843.      This function checks whether FEATURE is present in the current
  844.      XEmacs session (using `(featurep FEATURE)'; see below).  If it is
  845.      not, then `require' loads FILENAME with `load'.  If FILENAME is
  846.      not supplied, then the name of the symbol FEATURE is used as the
  847.      file name to load.
  848.  
  849.      If loading the file fails to provide FEATURE, `require' signals an
  850.      error, `Required feature FEATURE was not provided'.
  851.  
  852.  - Function: featurep FEATURE
  853.      This function returns `t' if FEATURE has been provided in the
  854.      current XEmacs session (i.e., FEATURE is a member of `features'.)
  855.  
  856.  - Variable: features
  857.      The value of this variable is a list of symbols that are the
  858.      features loaded in the current XEmacs session.  Each symbol was
  859.      put in this list with a call to `provide'.  The order of the
  860.      elements in the `features' list is not significant.
  861.  
  862. 
  863. File: lispref.info,  Node: Unloading,  Next: Hooks for Loading,  Prev: Named Features,  Up: Loading
  864.  
  865. Unloading
  866. =========
  867.  
  868.    You can discard the functions and variables loaded by a library to
  869. reclaim memory for other Lisp objects.  To do this, use the function
  870. `unload-feature':
  871.  
  872.  - Command: unload-feature FEATURE &optional FORCE
  873.      This command unloads the library that provided feature FEATURE.
  874.      It undefines all functions, macros, and variables defined in that
  875.      library with `defconst', `defvar', `defun', `defmacro',
  876.      `defsubst', `definf-function' and `defalias'.  It then restores
  877.      any autoloads formerly associated with those symbols.  (Loading
  878.      saves these in the `autoload' property of the symbol.)
  879.  
  880.      Ordinarily, `unload-feature' refuses to unload a library on which
  881.      other loaded libraries depend.  (A library A depends on library B
  882.      if A contains a `require' for B.)  If the optional argument FORCE
  883.      is non-`nil', dependencies are ignored and you can unload any
  884.      library.
  885.  
  886.    The `unload-feature' function is written in Lisp; its actions are
  887. based on the variable `load-history'.
  888.  
  889.  - Variable: load-history
  890.      This variable's value is an alist connecting library names with the
  891.      names of functions and variables they define, the features they
  892.      provide, and the features they require.
  893.  
  894.      Each element is a list and describes one library.  The CAR of the
  895.      list is the name of the library, as a string.  The rest of the
  896.      list is composed of these kinds of objects:
  897.  
  898.         * Symbols that were defined by this library.
  899.  
  900.         * Lists of the form `(require . FEATURE)' indicating features
  901.           that were required.
  902.  
  903.         * Lists of the form `(provide . FEATURE)' indicating features
  904.           that were provided.
  905.  
  906.      The value of `load-history' may have one element whose CAR is
  907.      `nil'.  This element describes definitions made with `eval-buffer'
  908.      on a buffer that is not visiting a file.
  909.  
  910.    The command `eval-region' updates `load-history', but does so by
  911. adding the symbols defined to the element for the file being visited,
  912. rather than replacing that element.
  913.  
  914. 
  915. File: lispref.info,  Node: Hooks for Loading,  Prev: Unloading,  Up: Loading
  916.  
  917. Hooks for Loading
  918. =================
  919.  
  920.  - Variable: after-load-alist
  921.      An alist of expressions to evaluate if and when particular
  922.      libraries are loaded.  Each element looks like this:
  923.  
  924.           (FILENAME FORMS...)
  925.  
  926.      When `load' is run and the file-name argument is FILENAME, the
  927.      FORMS in the corresponding element are executed at the end of
  928.      loading.
  929.  
  930.      FILENAME must match exactly!  Normally FILENAME is the name of a
  931.      library, with no directory specified, since that is how `load' is
  932.      normally called.  An error in FORMS does not undo the load, but
  933.      does prevent execution of the rest of the FORMS.
  934.  
  935.  
  936. 
  937. File: lispref.info,  Node: Byte Compilation,  Next: Debugging,  Prev: Loading,  Up: Top
  938.  
  939. Byte Compilation
  940. ****************
  941.  
  942.    XEmacs Lisp has a "compiler" that translates functions written in
  943. Lisp into a special representation called "byte-code" that can be
  944. executed more efficiently.  The compiler replaces Lisp function
  945. definitions with byte-code.  When a byte-coded function is called, its
  946. definition is evaluated by the "byte-code interpreter".
  947.  
  948.    Because the byte-compiled code is evaluated by the byte-code
  949. interpreter, instead of being executed directly by the machine's
  950. hardware (as true compiled code is), byte-code is completely
  951. transportable from machine to machine without recompilation.  It is not,
  952. however, as fast as true compiled code.
  953.  
  954.    In general, any version of Emacs can run byte-compiled code produced
  955. by recent earlier versions of Emacs, but the reverse is not true.  In
  956. particular, if you compile a program with Emacs 19.29, the compiled
  957. code does not run in earlier versions.  Files compiled in versions
  958. before 19.29 may not work in 19.29 if they contain character constants
  959. with modifier bits, because the bits were renumbered in Emacs 19.29.
  960.  
  961.    *Note Compilation Errors::, for how to investigate errors occurring
  962. in byte compilation.
  963.  
  964. * Menu:
  965.  
  966. * Speed of Byte-Code::          An example of speedup from byte compilation.
  967. * Compilation Functions::       Byte compilation functions.
  968. * Docs and Compilation::        Dynamic loading of documentation strings.
  969. * Dynamic Loading::             Dynamic loading of individual functions.
  970. * Eval During Compile::      Code to be evaluated when you compile.
  971. * Compiled-Function Objects::    The data type used for byte-compiled functions.
  972. * Disassembly::                 Disassembling byte-code; how to read byte-code.
  973.  
  974. 
  975. File: lispref.info,  Node: Speed of Byte-Code,  Next: Compilation Functions,  Up: Byte Compilation
  976.  
  977. Performance of Byte-Compiled Code
  978. =================================
  979.  
  980.    A byte-compiled function is not as efficient as a primitive function
  981. written in C, but runs much faster than the version written in Lisp.
  982. Here is an example:
  983.  
  984.      (defun silly-loop (n)
  985.        "Return time before and after N iterations of a loop."
  986.        (let ((t1 (current-time-string)))
  987.          (while (> (setq n (1- n))
  988.                    0))
  989.          (list t1 (current-time-string))))
  990.      => silly-loop
  991.      
  992.      (silly-loop 100000)
  993.      => ("Fri Mar 18 17:25:57 1994"
  994.          "Fri Mar 18 17:26:28 1994")  ; 31 seconds
  995.      
  996.      (byte-compile 'silly-loop)
  997.      => [Compiled code not shown]
  998.      
  999.      (silly-loop 100000)
  1000.      => ("Fri Mar 18 17:26:52 1994"
  1001.          "Fri Mar 18 17:26:58 1994")  ; 6 seconds
  1002.  
  1003.    In this example, the interpreted code required 31 seconds to run,
  1004. whereas the byte-compiled code required 6 seconds.  These results are
  1005. representative, but actual results will vary greatly.
  1006.  
  1007. 
  1008. File: lispref.info,  Node: Compilation Functions,  Next: Docs and Compilation,  Prev: Speed of Byte-Code,  Up: Byte Compilation
  1009.  
  1010. The Compilation Functions
  1011. =========================
  1012.  
  1013.    You can byte-compile an individual function or macro definition with
  1014. the `byte-compile' function.  You can compile a whole file with
  1015. `byte-compile-file', or several files with `byte-recompile-directory'
  1016. or `batch-byte-compile'.
  1017.  
  1018.    When you run the byte compiler, you may get warnings in a buffer
  1019. called `*Compile-Log*'.  These report things in your program that
  1020. suggest a problem but are not necessarily erroneous.
  1021.  
  1022.    Be careful when byte-compiling code that uses macros.  Macro calls
  1023. are expanded when they are compiled, so the macros must already be
  1024. defined for proper compilation.  For more details, see *Note Compiling
  1025. Macros::.
  1026.  
  1027.    Normally, compiling a file does not evaluate the file's contents or
  1028. load the file.  But it does execute any `require' calls at top level in
  1029. the file.  One way to ensure that necessary macro definitions are
  1030. available during compilation is to require the file that defines them
  1031. (*note Named Features::.).  To avoid loading the macro definition files
  1032. when someone *runs* the compiled program, write `eval-when-compile'
  1033. around the `require' calls (*note Eval During Compile::.).
  1034.  
  1035.  - Function: byte-compile SYMBOL
  1036.      This function byte-compiles the function definition of SYMBOL,
  1037.      replacing the previous definition with the compiled one.  The
  1038.      function definition of SYMBOL must be the actual code for the
  1039.      function; i.e., the compiler does not follow indirection to
  1040.      another symbol.  `byte-compile' returns the new, compiled
  1041.      definition of SYMBOL.
  1042.  
  1043.      If SYMBOL's definition is a compiled-function object,
  1044.      `byte-compile' does nothing and returns `nil'.  Lisp records only
  1045.      one function definition for any symbol, and if that is already
  1046.      compiled, non-compiled code is not available anywhere.  So there
  1047.      is no way to "compile the same definition again."
  1048.  
  1049.           (defun factorial (integer)
  1050.             "Compute factorial of INTEGER."
  1051.             (if (= 1 integer) 1
  1052.               (* integer (factorial (1- integer)))))
  1053.           => factorial
  1054.           
  1055.           (byte-compile 'factorial)
  1056.                =>
  1057.           #<byte-code (integer)
  1058.            "┴U½é┴ç┬S!_ç"
  1059.            [integer 1 factorial]
  1060.            3 "Compute factorial of INTEGER.">
  1061.  
  1062.      The result is a compiled-function object.  The string it contains
  1063.      is the actual byte-code; each character in it is an instruction or
  1064.      an operand of an instruction.  The vector contains all the
  1065.      constants, variable names and function names used by the function,
  1066.      except for certain primitives that are coded as special
  1067.      instructions.
  1068.  
  1069.  - Command: compile-defun &optional ARG
  1070.      This command reads the defun containing point, compiles it, and
  1071.      evaluates the result.  If you use this on a defun that is actually
  1072.      a function definition, the effect is to install a compiled version
  1073.      of that function.
  1074.  
  1075.      If ARG is non-`nil', the result is inserted in the current buffer
  1076.      after the form; otherwise, it is printed in the minibuffer.
  1077.  
  1078.  - Command: byte-compile-file FILENAME &optional LOAD
  1079.      This function compiles a file of Lisp code named FILENAME into a
  1080.      file of byte-code.  The output file's name is made by appending
  1081.      `c' to the end of FILENAME.
  1082.  
  1083.      If `load' is non-`nil', the file is loaded after having been
  1084.      compiled.
  1085.  
  1086.      Compilation works by reading the input file one form at a time.
  1087.      If it is a definition of a function or macro, the compiled
  1088.      function or macro definition is written out.  Other forms are
  1089.      batched together, then each batch is compiled, and written so that
  1090.      its compiled code will be executed when the file is read.  All
  1091.      comments are discarded when the input file is read.
  1092.  
  1093.      This command returns `t'.  When called interactively, it prompts
  1094.      for the file name.
  1095.  
  1096.           % ls -l push*
  1097.           -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
  1098.           
  1099.           (byte-compile-file "~/emacs/push.el")
  1100.                => t
  1101.           
  1102.           % ls -l push*
  1103.           -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
  1104.           -rw-rw-rw-  1 lewis     638 Oct  8 20:25 push.elc
  1105.  
  1106.  - Command: byte-recompile-directory DIRECTORY &optional FLAG
  1107.      This function recompiles every `.el' file in DIRECTORY that needs
  1108.      recompilation.  A file needs recompilation if a `.elc' file exists
  1109.      but is older than the `.el' file.
  1110.  
  1111.      When a `.el' file has no corresponding `.elc' file, then FLAG says
  1112.      what to do.  If it is `nil', these files are ignored.  If it is
  1113.      non-`nil', the user is asked whether to compile each such file.
  1114.  
  1115.      The returned value of this command is unpredictable.
  1116.  
  1117.  - Function: batch-byte-compile
  1118.      This function runs `byte-compile-file' on files specified on the
  1119.      command line.  This function must be used only in a batch
  1120.      execution of Emacs, as it kills Emacs on completion.  An error in
  1121.      one file does not prevent processing of subsequent files.  (The
  1122.      file that gets the error will not, of course, produce any compiled
  1123.      code.)
  1124.  
  1125.           % emacs -batch -f batch-byte-compile *.el
  1126.  
  1127.  - Function: batch-byte-recompile-directory
  1128.      This function is similar to `batch-byte-compile' but runs the
  1129.      command `byte-recompile-directory' on the files remaining on the
  1130.      command line.
  1131.  
  1132.  - Variable: byte-recompile-directory-ignore-errors-p
  1133.      If non-`nil', this specifies that `byte-recompile-directory' will
  1134.      continue compiling even when an error occurs in a file.  This is
  1135.      normally `nil', but is bound to `t' by
  1136.      `batch-byte-recompile-directory'.
  1137.  
  1138.  - Function: byte-code CODE-STRING DATA-VECTOR MAX-STACK
  1139.      This function actually interprets byte-code.  A byte-compiled
  1140.      function is actually defined with a body that calls `byte-code'.
  1141.      Don't call this function yourself.  Only the byte compiler knows
  1142.      how to generate valid calls to this function.
  1143.  
  1144.      In newer Emacs versions (19 and up), byte-code is usually executed
  1145.      as part of a compiled-function object, and only rarely due to an
  1146.      explicit call to `byte-code'.
  1147.  
  1148. 
  1149. File: lispref.info,  Node: Docs and Compilation,  Next: Dynamic Loading,  Prev: Compilation Functions,  Up: Byte Compilation
  1150.  
  1151. Documentation Strings and Compilation
  1152. =====================================
  1153.  
  1154.    Functions and variables loaded from a byte-compiled file access their
  1155. documentation strings dynamically from the file whenever needed.  This
  1156. saves space within Emacs, and makes loading faster because the
  1157. documentation strings themselves need not be processed while loading the
  1158. file.  Actual access to the documentation strings becomes slower as a
  1159. result, but normally not enough to bother users.
  1160.  
  1161.    Dynamic access to documentation strings does have drawbacks:
  1162.  
  1163.    * If you delete or move the compiled file after loading it, Emacs
  1164.      can no longer access the documentation strings for the functions
  1165.      and variables in the file.
  1166.  
  1167.    * If you alter the compiled file (such as by compiling a new
  1168.      version), then further access to documentation strings in this
  1169.      file will give nonsense results.
  1170.  
  1171.    If your site installs Emacs following the usual procedures, these
  1172. problems will never normally occur.  Installing a new version uses a new
  1173. directory with a different name; as long as the old version remains
  1174. installed, its files will remain unmodified in the places where they are
  1175. expected to be.
  1176.  
  1177.    However, if you have built Emacs yourself and use it from the
  1178. directory where you built it, you will experience this problem
  1179. occasionally if you edit and recompile Lisp files.  When it happens, you
  1180. can cure the problem by reloading the file after recompiling it.
  1181.  
  1182.    Byte-compiled files made with Emacs 19.29 will not load into older
  1183. versions because the older versions don't support this feature.  You can
  1184. turn off this feature by setting `byte-compile-dynamic-docstrings' to
  1185. `nil'.  Once this is done, you can compile files that will load into
  1186. older Emacs versions.  You can do this globally, or for one source file
  1187. by specifying a file-local binding for the variable.  Here's one way to
  1188. do that:
  1189.  
  1190.      -*-byte-compile-dynamic-docstrings: nil;-*-
  1191.  
  1192.  - Variable: byte-compile-dynamic-docstrings
  1193.      If this is non-`nil', the byte compiler generates compiled files
  1194.      that are set up for dynamic loading of documentation strings.
  1195.  
  1196.    The dynamic documentation string feature writes compiled files that
  1197. use a special Lisp reader construct, `#@COUNT'.  This construct skips
  1198. the next COUNT characters.  It also uses the `#$' construct, which
  1199. stands for "the name of this file, as a string."  It is best not to use
  1200. these constructs in Lisp source files.
  1201.  
  1202.